home *** CD-ROM | disk | FTP | other *** search
/ Software Explosion 2 / Software Explosion 2 - Virtual Computer Pets (1997).iso / system / c / biganim_docs < prev    next >
Encoding:
Text File  |  1996-09-09  |  7.9 KB  |  225 lines
  1.  
  2.             *--------------*
  3.             | BigAnim v3.5 |
  4.             *==============*
  5.  
  6.  
  7.     What is BigAnim?
  8.     ~~~~~~~~~~~~~~~~
  9. BigAnim is an animation player (you guessed it!), and it's called that
  10. because it is able to display animations that are too large to be loaded
  11. into memory directly.
  12.  
  13. The two most important features of BigAnim are:
  14.  
  15. o BigAnim loads the animation asynchronously, 100 KByte at a time, which
  16.   means that while it displays one 100 KByte part of the animation, it is
  17.   loading the next 100 KByte simultaneously.
  18.  
  19. o If you're using Kickstart 3.0 or later, BigAnim will use the new double-
  20.   buffering routines in graphics.library. If you're not, BigAnim will take
  21.   over the display from Intuition, to increase playback speed. However, if
  22.   you flip screens, or pull down BigAnim's screen, BigAnim will detect
  23.   this, and use the old, intuition-friendly (and slow!) routines instead.
  24.  
  25.  
  26.     Usage
  27.     ~~~~~
  28. BigAnim can only be run from a CLI or shell, and the usage is:
  29.  
  30.     BigAnim filename [LOADALL] [HIRES] [BLANK] [VERBOSE]
  31.                      [BUFSIZE n] [RELTIME n] [TASKPRI n]
  32.  
  33. where "filename" should refer to an ANIM type 5 or 7 animation. ANIM
  34. type 8 is not supported, due to its relative inefficiency compared to
  35. ANIM type 7. For best results, type 8 animations should be converted to
  36. type 7.
  37.  
  38.  
  39.     Options
  40.     ~~~~~~~
  41.     LOADALL
  42.  
  43. Tells BigAnim to load the whole animation before starting playback.
  44. Note that the animation is loaded in chunks, and the size of these
  45. chunks can be set with the BUFSIZE keyword.
  46.  
  47.     HIRES
  48.  
  49. Forces the screen resolution to Hires/Interlace. This will only work
  50. if the original resolution was lores/nolace.
  51.  
  52.     BLANK
  53.  
  54. Blanks the mouse pointer.
  55.  
  56.     VERBOSE
  57.  
  58. BigAnim prints some info about the animation, such as screen size/depth,
  59. display modes, animation type, etc.
  60.  
  61. Example:                Explanation:
  62.  
  63. File:     Juggler            File name
  64. Picture:  320 x 200 (48000 bytes)    Picture size (width, height & bytes)
  65. Display:  320 x 200 x 6 planes        Display resolution & depth
  66. Modes:    LORES HAM            View modes
  67. AnimType: 5                Anim type: 5, 7 (short) or 7 (long)
  68. Length:   24 frames            The number of frames in the anim
  69. Speed:    48 fps            Actual playback speed (frames/second)
  70. BufUsage: 94-99 %            Buffer utilization percentage (min-max)
  71.  
  72. Note: The actual numbers for the last four lines won't be printed until
  73. the animation has been displayed once (twice for the "Speed" and "BufUsage"
  74. numbers), simply because that information isn't available until then.
  75. The "BufUsage" numbers will not be printed if you're using the LOADALL switch.
  76.  
  77.     BUFSIZE n
  78.  
  79. Sets the buffer size to n bytes. The default is 100 K (102400 bytes), which
  80. means that BigAnim loads 100 K at a time.
  81.  
  82.     RELTIME n
  83.  
  84. Sets the playback timing, in 1/50 seconds if you're running on a PAL
  85. system, or 1/60 for NTSC systems.
  86.  
  87.     TASKPRI n
  88.  
  89. This sets BigAnim's task priority during playback. If your hard disk
  90. controller doesn't use DMA, the playback will probably be less jerky if
  91. you use a high task priority. The best value for priority is generally
  92. the same as the file system or the hard disk driver uses. Actually,
  93. TASKPRI can be used with good results even on DMA controllers: On my
  94. setup with an A590 and a Quantum LP240S, the playback becomes somewhat
  95. smoother when I use TASKPRI 11.
  96.  
  97.  
  98.     Keys
  99.     ~~~~
  100. While the animation is being played, you can press the following keys:
  101.  
  102. ESC       - Quits BigAnim (you can also use the right mouse button)
  103. Space     - Pauses the animation, or restarts if already paused
  104. N         - If paused, displays the next frame
  105. TAB       - Toggles colour cycling
  106. Shift TAB - Turns off cycling and restores the original colour map
  107. 0-9       - Changes playback speed. By pressing one of the keys 1-9 you
  108.             can directly set the RELTIME value during playback. If you
  109.             press 0, BigAnim will use the timing information stored in
  110.             the animation.
  111.  
  112.  
  113.     Environment
  114.     ~~~~~~~~~~~
  115. If you want to use certain options or settings as default, you can save
  116. them in an environment variable called BIGANIMOPTS. So, for instance, if
  117. you always want to use a buffer size of 204800 bytes, do:
  118.  
  119.     SetEnv BIGANIMOPTS BUFSIZE 204800
  120.  
  121. and BigAnim will use that instead of the built-in default of 102400 bytes.
  122. Values for BUFSIZE, RELTIME and TASKPRI set via BIGANIMOPTS can be over-
  123. ridden with the respective command line options. All options except LOADALL
  124. can be used in BIGANIMOPTS.
  125.  
  126.  
  127.     Additional info
  128.     ~~~~~~~~~~~~~~~
  129. o BigAnim supports CMAP chunks internal to the animation, and changes the
  130.   screen colors accordingly. 
  131.  
  132. o BigAnim uses the RelTime field of the ANHD chunk to decide how much
  133.   delay to put between frames. You can override this value by specifying
  134.   a new value with the RELTIME keyword, or by pressing a number key during
  135.   playback.
  136.  
  137. o BigAnim uses two sets of specially optimised decompression routines,
  138.   for processors with and without code cache.
  139.  
  140.  
  141.     How to choose the best buffer size
  142.     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  143. To maximize playback speed, do this: If you have enough memory in your
  144. Amiga to load the entire animation, use the LOADALL switch. This will
  145. lead to the fastest possible playback. If you don't have that much
  146. memory, you can try different buffer sizes with the BUFSIZE keyword.
  147. Tip: If you use the VERBOSE option, BigAnim will measure the playback
  148. speed, so you can easily see how different buffer sizes affect playback.
  149. Also, the "BufUsage" numbers will tell you how well the buffers are
  150. utilized during playback.
  151.  
  152. When choosing buffer size, please keep these facts in mind:
  153.  
  154. 1. Due to the asynchronous nature of BigAnim's loading method, using
  155. the largest possible buffer size may not give the fastest playback.
  156.  
  157. 2. Certain combinations of file size and buffer size should be avoided.
  158. An example: If you use a buffer size of 300 KBytes with an animation
  159. that's 1000 KBytes long, then the first three reads will read 300 KBytes
  160. each, but the fourth will only read 100 KBytes. This is clearly not
  161. optimal. It would be much better to use a buffer size of 250 or 334
  162. KBytes (or just a little bit more, to be on the safe side). So, in
  163. cases when the last read of an animation is less than half as long as
  164. the others, BigAnim will print a warning message: "non-optimal buffer
  165. size".
  166.  
  167. There are two common problems often encountered while trying to find the
  168. ideal settings:
  169.  
  170. Common problem #1: Sometimes the playback stops for a while, then continues.
  171.  
  172. Reason: Either (1) your hard disk cannot read fast enough to keep up with
  173. the playback, (2) your hard disk doesn't have enough buffers, or (3) the hard
  174. disk driver uses all available CPU time so the playback stops.
  175.  
  176. Solution: (1) Increase buffer size, and/or use RELTIME to slow down play-
  177. back so the hard disk can keep up. (2) Use "AddBuffers" to add more buffers
  178. to your hard disk. BigAnim uses the DOS "Seek" function from time to time, and
  179. the "Seek" operation will be much faster if you have enough buffers. "Enough"
  180. is approximately one buffer for every 36 KBytes of data in the animation file.
  181. (3) Use TASKPRI to increase BigAnim's task priority. Usually, using the same
  182. priority that the hard disk driver uses will give the best results.
  183.  
  184. Common problem #2: Now and then the playback slows down temporarily.
  185.  
  186. Reason: Due to hard disk transfer, the decompression can't be done at full
  187. speed.
  188.  
  189. Solution: Use RELTIME to slow down playback. The playback will of course
  190. be slower, but not as jerky as before.
  191.  
  192.  
  193.     Future additions
  194.     ~~~~~~~~~~~~~~~~
  195. I am currently working on additions to the IFF ANIM standard, so that IFF
  196. 8SVX sounds can be stored inside the animation file, and played at certain
  197. points in the animation. Future versions of BigAnim will support this, and
  198. possibly also loops, so that parts of an animation can be played back
  199. repeatedly.
  200.  
  201.  
  202.     Disclaimer
  203.     ~~~~~~~~~~
  204. #include <std/disclaimer.h>
  205.  
  206.  
  207.     Distribution
  208.     ~~~~~~~~~~~~
  209. BigAnim is freely distributable, as long as BigAnim and all related files
  210. are distributed unchanged.
  211.  
  212.  
  213.     Feedback
  214.     ~~~~~~~~
  215. If you want to send me suggestions, bug reports, etc, I can
  216. be reached at:
  217.  
  218. Internet:    d8sunch@dtek.chalmers.se
  219.  
  220. Snail-mail:    Christer Sundin
  221.         7321 Bollestad
  222.         S-442 93 Kungälv
  223.         Sweden
  224.  
  225.